/*
 * 代号：凤凰
 * http://www.jphenix.org
 * 2014-06-13
 * V4.0
 */
package com.jphenix.standard.servlet.api;

import java.io.BufferedReader;
import java.io.IOException;
import java.security.Principal;
import java.util.Enumeration;
import java.util.Locale;
import java.util.Map;

import com.jphenix.standard.docs.ClassInfo;

/**
 * 页面请求扩展接口
 * 
 * 2022-09-04 隔离了ServletApi，兼容新老Tomcat
 * 2022-09-05 合并了假请求接口
 * 2022-09-07 将接口中高风险方法迁移到了IRequestManager接口中
 * 
 * @author 刘虻
 * 2011-5-4 下午01:48:32
 */
@ClassInfo({"2022-09-07 13:09","页面请求扩展接口"})
public interface IRequest {

    /**
     * 设置传入参数
     * @param key      参数主键
     * @param value    参数值数组
     * 2014年6月12日
     * @author 马宝刚
     */
    void setParameter(String key,String[] value);
    
    /**
     * 设置传入参数
     * @param key      参数主键
     * @param value    参数值
     * 2014年6月12日
     * @author 马宝刚
     */
    void setParameter(String key,String value);
    
	
	/**
	 * 设置是否禁止使用页面请求外壳（主要用于过滤）
	 * 刘虻
	 * 2010-8-2 下午03:25:07
	 * @param disabled 是否禁止使用页面请求外壳
	 */
	void setDisabledWrapper(boolean disabled);
	
	/**
     * 获取客户端IP地址信息 简称：cip
     * @return 客户端IP地址信息
     * 2014年4月15日
     * @author 马宝刚
     */
    String getClientIP();
    
    
	/**
	 * 获取客户端IP地址信息 全称：getClientIP
	 * @return 客户端IP地址信息
	 * 2014年4月15日
	 * @author 马宝刚
	 */
    String cip();
    
    /**
     * 获取头信息容器
     * @return 头信息容器
     * 2014年9月5日
     * @author 马宝刚
     */
    Map<String,String> getHeaderMap();
    
    /**
     * 是否缓存提交值
     * @return 是否缓存提交值
     * 2014年9月5日
     * @author 马宝刚
     */
    boolean isBuffered();
    
    /**
     * 获取提交数据字节数组
     * @return 提交数据字节数组
     * 2014年9月5日
     * @author 马宝刚
     */
    byte[] getPostData();
    
    /**
     * 获取网站根路径
     * @return 网站根路径
     * 2016年3月11日
     * @author 马宝刚
     */
    String getWebBasePath();
    
	/**
	 * 获取指定的Cookie值
	 * @param key 主键
	 * @return 值
	 * 2017年3月1日
	 * @author MBG
	 */
	String getCookieValue(String key);
	
	/**
	 * 请求方式是否为get
	 * @return 请求方式是否为get
	 * 2017年5月1日
	 * @author MBG
	 */
	boolean isGet();
	
	/**
	 * 请求方式是否为POST
	 * @return 请求方式是否为POST
	 * 2017年5月1日
	 * @author MBG
	 */
	boolean isPost();
	
	/**
	 * 获取请求URL中提交的参数容器
	 * @return 请求URL中提交的参数容器
	 * 2018年3月2日
	 * @author MBG
	 */
	Map<String,String> getUrlParameterMap();
	
	/**
	 * 从请求URL中获取指定的参数值
	 * @param key 参数主键
	 * @return    参数值
	 * 2018年3月2日
	 * @author MBG
	 */
	String getUrlParameter(String key);
	
	//#region 以下是原标准接口中的方法
	
	/**
	 * 获取对应的属性值
	 * @param name 属性名
	 * @return     属性值
	 * 2022年8月22日
	 * @author MBG
	 */
	Object getAttribute(String name);
	
	/**
	 * 获取属性名枚举
	 * @return 属性名枚举
	 * 2022年8月22日
	 * @author MBG
	 */
	Enumeration<String> getAttributeNames();
	
	/**
	 * 获取请求数据编码
	 * @return 编码
	 * 2022年8月22日
	 * @author MBG
	 */
	String getCharacterEncoding();
	
	/**
	 * 设置请求参数编码
	 * @param env 编码
	 * 2022年8月22日
	 * @author MBG
	 */
	void setCharacterEncoding(String env);
	
	/**
	 * 获取请求数据长度
	 * @return 请求数据长度
	 * 2022年8月22日
	 * @author MBG
	 */
	int getContentLength();
	
	/**
	 * 获取请求数据长度
	 * @return 请求数据长度
	 * 2022年8月22日
	 * @author MBG
	 */
	long getContentLengthLong();
	
	/**
	 * 获取请求数据类型
	 * @return 请求数据类型
	 * 2022年8月22日
	 * @author MBG
	 */
	String getContentType();
	
	/**
	 * 获取请求数据流
	 * @return 请求数据流
	 * @throws IOException 异常
	 * 2022年8月22日
	 * @author MBG
	 */
	ServletInputStream iGetInputStream() throws IOException;
	
	/**
	 * 获取指定请求参数值
	 * @param name 参数名
	 * @return     参数值
	 * 2022年8月22日
	 * @author MBG
	 */
	String getParameter(String name);
	
	/**
	 * 获取请求参数名枚举
	 * @return 请求参数名枚举
	 * 2022年8月22日
	 * @author MBG
	 */
	Enumeration<String> getParameterNames();
	
	/**
	 * 获取指定请求参数值
	 * @param name 参数名
	 * @return     参数值
	 * 2022年8月22日
	 * @author MBG
	 */
	String[] getParameterValues(String name);
	
	/**
	 * 获取请求参数容器
	 * @return 请求参数容器
	 * 2022年8月22日
	 * @author MBG
	 */
	Map<String, String[]> getParameterMap();
	
	/**
	 * 获取请求协议名
	 * @return 请求协议名
	 * 2022年8月22日
	 * @author MBG
	 */
	String getProtocol();
	
	/**
	 * 获取请求协议名
	 * @return 请求协议名
	 * 2022年8月22日
	 * @author MBG
	 */
	String getScheme();
	
	/**
	 * 获取服务器名
	 * @return 服务器名
	 * 2022年8月22日
	 * @author MBG
	 */
	String getServerName();
	
	/**
	 * 获取请求端口号
	 * @return 请求端口号
	 * 2022年8月22日
	 * @author MBG
	 */
	int getServerPort();
	
	/**
	 * 获取缓存读取类
	 * @return 缓存读取类
	 * @throws IOException 异常
	 * 2022年8月22日
	 * @author MBG
	 */
	BufferedReader getReader() throws IOException;
	
	/**
	 * 获取客户端地址
	 * @return 客户端地址
	 * 2022年8月22日
	 * @author MBG
	 */
	String getRemoteAddr();
	
	/**
	 * 获取客户端host
	 * @return 客户端host
	 * 2022年8月22日
	 * @author MBG
	 */
	String getRemoteHost();
	
	/**
	 * 设置属性值
	 * @param name 属性名
	 * @param o    属性值
	 * 2022年8月22日
	 * @author MBG
	 */
	void setAttribute(String name, Object o);
	
	/**
	 * 移除指定属性值
	 * @param name 属性名
	 * 2022年8月22日
	 * @author MBG
	 */
	void removeAttribute(String name);
	
	/**
	 * 获取语言相关信息
	 * @return 语言相关信息
	 * 2022年8月22日
	 * @author MBG
	 */
	Locale getLocale();
	
	/**
	 * 获取语言信息枚举
	 * @return 语言信息枚举
	 * 2022年8月22日
	 * @author MBG
	 */
	Enumeration<Locale> getLocales();
	
	/**
	 * 是否为安全请求
	 * @return 是否为安全请求
	 * 2022年8月22日
	 * @author MBG
	 */
	boolean isSecure();
	
	/**
	 * 获取转发请求对象
	 * @param path 资源路径
	 * @return     转发请求对象
	 * 2022年8月22日
	 * @author MBG
	 */
	IRequestDispatcher iGetRequestDispatcher(String path);
	
	/**
	 * 获取资源全路径
	 * @param path 相对路径
	 * @return     全路径
	 * 2022年8月22日
	 * @author MBG
	 */
	String getRealPath(String path);
	
	/**
	 * 获取客户端端口号
	 * @return 客户端端口号
	 * 2022年8月22日
	 * @author MBG
	 */
	int getRemotePort();
	
	/**
	 * 获取响应域名
	 * @return 响应域名
	 * 2022年8月22日
	 * @author MBG
	 */
	String getLocalName();
	
	/**
	 * 获取响应地址
	 * @return 响应地址
	 * 2022年8月22日
	 * @author MBG
	 */
	String getLocalAddr();
	
	/**
	 * 获取监听端口
	 * @return 监听端口
	 * 2022年8月22日
	 * @author MBG
	 */
	int getLocalPort();
	
    /**
     * getAuthType
     * @return getAuthType
     * 2022年8月24日
     * @author MBG
     */
    String getAuthType();

    /**
     * 返回所有Cookie对象数组
     * @return 所有Cookie对象数组
     * 2022年8月24日
     * @author MBG
     */
    ICookie[] iGetCookies();

    /**
     * 获取日期型报文头值
     * @param name 报文头名
     * @return     日期型报文头值
     * 2022年8月24日
     * @author MBG
     */
    long getDateHeader(String name);

    /**
     * 获取报文头值
     * @param name 报文头名
     * @return     值
     * 2022年8月24日
     * @author MBG
     */
    String getHeader(String name);

    /**
     * 获取同名报文头值枚举对象
     * @param name 报文头名
     * @return     值枚举对象
     * 2022年8月24日
     * @author MBG
     */
    Enumeration<String> getHeaders(String name);

    /**
     * 获取报文头名枚举对象
     * @return 报文头名枚举对象
     * 2022年8月24日
     * @author MBG
     */
    Enumeration<String> getHeaderNames();

    /**
     * 获取整型报文头值
     * @param name 报文头名
     * @return     报文头值
     * 2022年8月24日
     * @author MBG
     */
    int getIntHeader(String name);

    /**
     * 获取请求方法名 GET, POST, or PUT
     * @return 请求方法名
     * 2022年8月24日
     * @author MBG
     */
    String getMethod();

    /**
     * 获取路径信息
     * @return 路径信息
     * 2022年8月24日
     * @author MBG
     */
    String getPathInfo();

    /**
     * 获取解析后的路径信息
     * @return 解析后的路径信息
     * 2022年8月24日
     * @author MBG
     */
    String getPathTranslated();

    /**
     * 获取虚拟路径（上下文路径）
     * @return 虚拟路径
     * 2022年8月24日
     * @author MBG
     */
    String getContextPath();

    /**
     * 获取URL中的参数字符串
     * @return URL中的参数字符串
     * 2022年8月24日
     * @author MBG
     */
    String getQueryString();

    /**
     * 获取客户端请求用户信息
     * @return 客户端请求用户信息
     * 2022年8月24日
     * @author MBG
     */
    String getRemoteUser();

    /**
     * 用户是否受控
     * @param role 角色代码
     * @return     用户是否受控
     * 2022年8月24日
     * @author MBG
     */
    boolean isUserInRole(String role);

    /**
     * 获取Principal
     * @return Principal
     * 2022年8月24日
     * @author MBG
     */
    Principal getUserPrincipal();

    /**
     * 获取会话主键值
     * @return 会话主键值
     * 2022年8月24日
     * @author MBG
     */
    String getRequestedSessionId();

    /**
     * 获取请求路径（不带参数）
     * @return 请求路径
     * 2022年8月24日
     * @author MBG
     */
    String getRequestURI();

    /**
     * 获取完整URL
     * @return 完整URL
     * 2022年8月24日
     * @author MBG
     */
    StringBuffer getRequestURL();

    /**
     * 获取动作路径
     * @return 动作路径
     * 2022年8月24日
     * @author MBG
     */
    String getServletPath();
    
    /**
     * 设置动作路径（轻易不要用）
     * @param servletPath 动作路径
     * 2022年9月3日
     * @author MBG
     */
    void setServletPath(String servletPath);

    /**
     * 获取会话对象
     * @param create 是否新创建会话
     * @return 会话对象
     * 2022年8月24日
     * @author MBG
     */
    IHttpSession iGetSession(boolean create);

    /**
     * 获取会话对象
     * @return 会话对象
     * 2022年8月24日
     * @author MBG
     */
    IHttpSession iGetSession();

    /**
     * 会话主键是否无效
     * @return 会话主键是否无效
     * 2022年8月22日
     * @author MBG
     */
    boolean isRequestedSessionIdValid();

    /**
     * 是否从Cookie中获取的会话主键
     * @return 是否从Cookie中获取的会话主键
     * 2022年8月22日
     * @author MBG
     */
    boolean isRequestedSessionIdFromCookie();

    /**
     * 是否从ur中获取的会话主键
     * @return 是否从ur中获取的会话主键
     * 2022年8月22日
     * @author MBG
     */
    boolean isRequestedSessionIdFromURL();

	//#endregion
}
